﻿<?xml version="1.0" encoding="utf-8"?>
<developerConceptualDocument
	xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
	xmlns:xlink="http://www.w3.org/1999/xlink">
	
	<!--
  <summary>
    <para>Optional summary abstract</para>
  </summary>
  -->
	
	<introduction>
		<!-- Uncomment this to generate an outline of the section and sub-section
         titles.  Specify a numeric value as the inner text to limit it to
         a specific number of sub-topics when creating the outline.  Specify
         zero (0) to limit it to top-level sections only.  -->
		<!-- <autoOutline /> -->
		
		<para>The text editor makes use of several different coordinate systems.
		Here's an explanation of them.</para>
	</introduction>
	
	<!-- Add one or more top-level section elements.  These are collapsible.
       If using <autoOutline /> tag, add an address attribute to identify
       it so that it can be jumped to with a hyperlink. -->
	<section>
		<title>Offset</title>
		<content>
			<para>The number of characters from the start of the text, counting from 0.</para>
			<para>Same as used by String.IndexOf() etc.</para>
		</content>
	</section>
	<section>
		<title>TextLocation</title>
		<content>
			<para>A Line,Column pair. Line and column count from 1.</para>
			<para>Use the
				TextDocument.<codeEntityReference>M:ICSharpCode.AvalonEdit.Document.TextDocument.GetLocation(System.Int32)</codeEntityReference>
				and
				TextDocument.<codeEntityReference>M:ICSharpCode.AvalonEdit.Document.TextDocument.GetOffset(ICSharpCode.AvalonEdit.Document.TextLocation)</codeEntityReference>
			methods to convert between TextLocation and Offset.</para>
		</content>
	</section>
	<section>
		<title>TextAnchor</title>
		<content>
			<para>A text anchor object stores an Offset, but automatically
			updates the offset when text is inserted/removed before the offset.
			</para>
			<para>
			The document keeps weak references to anchors for updating them,
			so you don't have to worry about memory leaks using text anchors.
			</para>
			<para>Use the 
			<codeEntityReference>P:ICSharpCode.AvalonEdit.Document.TextAnchor.Offset</codeEntityReference>
				property to get the offset from a text anchor.
			Use the
			<codeEntityReference>M:ICSharpCode.AvalonEdit.Document.TextDocument.CreateAnchor(System.Int32)</codeEntityReference>
			method to create an anchor from an offset.
			</para>
		</content>
	</section>
	<section>
		<title>RelativeTextOffset</title>
		<content>
			<para>An offset in the document, but relative to the start offset of a VisualLine.</para>
			<para>Relative text offsets are used to store document offsets in visual lines.</para>
			<para>You can convert between relative text offsets and document offsets
			by adding/subtracting
			<codeEntityReference>T:ICSharpCode.AvalonEdit.Rendering.VisualLine</codeEntityReference>.<codeEntityReference>P:ICSharpCode.AvalonEdit.Rendering.VisualLine.FirstDocumentLine</codeEntityReference>.<codeEntityReference>P:ICSharpCode.AvalonEdit.Document.DocumentLine.Offset</codeEntityReference>.
			</para>
		</content>
	</section>
	<section>
		<title>VisualColumn</title>
		<content>
			<para>An integer value that specifies a position inside a VisualLine.</para>
			<para>
			Not only text has a length in the visual line, but also other VisualLineElements.
			VisualColumn is counting from 0 for each visual line.
			</para>
			<para>For example, tab markers take 2 visual columns (the marker and the tab space),
			newline markers take 1 visual column; folding markers take just 1 visual column
			even though they are longer in the document text.</para>
			<para>Use the
			<codeEntityReference>M:ICSharpCode.AvalonEdit.Rendering.VisualLine.GetVisualColumn(System.Int32)</codeEntityReference>
			and 
			<codeEntityReference>M:ICSharpCode.AvalonEdit.Rendering.VisualLine.GetRelativeOffset(System.Int32)</codeEntityReference>
			methods to convert between
			visual columns and relative text offsets.</para>
		
			<alert class="note">
				<para>Do not confuse VisualColumn with text columns.
				VisualColumn starts at 0, text column at 1. Text may have different length
				in the two coordinate systems (e.g. tab markers, foldings).</para>
			</alert>
		</content>
	</section>
	<section>
		<title>TextViewPosition</title>
		<content>
			<para>A Line,Column,VisualColumn triple.</para>
			<para>Can be implicitly converted
			to TextLocation, but has the additional VisualColumn information
			that is necessary to accurately hold the caret position when
			VisualLineElements with DocumentLength 0 are in use.</para>
		</content>
	</section>
	<section>
		<title>VisualTop</title>
		<content>
			<para>A double value that specifies the distance from the top of
			the document to the top of a line measured in device-independent pixels.</para>
			<para>VisualTop is equivalent to the Y component of a VisualPosition.</para>
		</content>
	</section>
	<section>
		<title>VisualPosition</title>
		<content>
			<para>A Point value (double X,Y) that specifies the position of an
			element from the top left document corner measured in device-independent pixels.</para>
			<para>To convert a VisualPosition to or from a (mouse) position inside
			the TextView, simply subtract or add
			TextView.<codeEntityReference>P:ICSharpCode.AvalonEdit.Rendering.TextView.ScrollOffset</codeEntityReference>
			to it.
			</para>
		</content>
	</section>
	
	<relatedTopics>
		<!-- One or more of the following:
         - A local link
         - An external link
         - A code entity reference

    <link xlink:href="Other Topic's ID"/>
    <link xlink:href="Other Topic's ID">Link inner text</link>

    <externalLink>
        <linkText>Link text</linkText>
        <linkAlternateText>Optional alternate link text</linkAlternateText>
        <linkUri>URI</linkUri>
    </externalLink>

    <codeEntityReference>API member ID</codeEntityReference>

    Examples:

    <link xlink:href="00e97994-e9e6-46e0-b420-5be86b2f8270" />
    <link xlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Some other topic</link>

    <externalLink>
        <linkText>SHFB on CodePlex</linkText>
        <linkAlternateText>Go to CodePlex</linkAlternateText>
        <linkUri>http://www.codeplex.com/SHFB</linkUri>
    </externalLink>

    <codeEntityReference>T:TestDoc.TestClass</codeEntityReference>
    <codeEntityReference>P:TestDoc.TestClass.SomeProperty</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.#ctor</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.#ctor(System.String,System.Int32)</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.ToString</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.FirstMethod</codeEntityReference>
    <codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>
    -->
	</relatedTopics>
</developerConceptualDocument>
